home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Topik / Topik - Disk 08 - TOPIKless (19xx)(Topik Public Domain)(PD)[WB].zip / Topik - Disk 08 - TOPIKless (19xx)(Topik Public Domain)(PD)[WB].adf / PowerPacker / Packer.doc < prev    next >
Text File  |  1989-07-02  |  19KB  |  438 lines
  1.  
  2.  
  3.  
  4.                        Power Packer V2.1a User Manual
  5.  
  6.                                March 14, 1989
  7.  
  8.  
  9.  
  10. Preface
  11. =======
  12.  
  13.      Congratulations, you have just obtained a copy of Power Peak's new and
  14. improved PowerPacker 2.1a.  If you have suggestions or remarks about this
  15. program, or if you find any bugs, please let me know.
  16.      This version of the PowerPacker is shareware, this means that if you use
  17. it a lot I would appreciate it if you'd send me a contribution of $10 or the
  18. same amount in any other currency.  This money will enable me to produce more
  19. programs on the Amiga.  If you send $15 I will send you the latest version of
  20. the PowerPacker.
  21.      Write to the following address:
  22.  
  23.                                 François Nico
  24.                                 Corbielaan 13
  25.                              3060 Bertem BELGIUM
  26.  
  27.  
  28. Contents
  29. ========
  30.  
  31. 1. The Packer
  32.      1.1 An introduction
  33.      1.2 The file requester
  34.      1.3 The basic menus
  35.           1.3.1 Project
  36.           1.3.2 Prefs
  37.  
  38. 2. Recrunch
  39.      2.1 How ?
  40.      2.2 Why ?
  41.  
  42. 3. The HunkLab
  43.      3.1 Preferences
  44.      3.2 Process file
  45.  
  46. 4. The Script Menu
  47.  
  48. 5. The Supervisor Window
  49.  
  50. 6. A Sample Session
  51.  
  52. 7. PowerPacker 2.1a & the CLI
  53.  
  54.  
  55. 1. The Packer
  56. -------------
  57.  
  58. 1.1 An introduction
  59.  
  60.      The PowerPacker is a userfriendly command and data cruncher, this means
  61. a menu driven utility that can crunch almost any file on your disks.  When
  62. you use it for the first time it's best to maintain a certain order in your
  63. actions (as we will see in chapter 6 of this document):
  64.  
  65.   (a) set the packer options at the beginning of a session (Prefs menu)
  66.   (b) load the file from disk (Project menu)
  67.   (c) save the file back to disk (Project menu)
  68.  
  69.      Apart from the crunching, you can also recrunch files that were crunched
  70. by some other crunchers.
  71.      The HunkLab enables you to e.g. force code or data in chip ram.
  72.      The script, a new feature in 2.1a, allows you to e.g. crunch a dozen of
  73. files overnight.
  74.  
  75.      Before I demonstrate how to use the PowerPacker, let's look at the file
  76. requester and a brief overview of the menus and capabilities.
  77.  
  78.  
  79. 1.2 The file requester
  80.  
  81.     Whenever you are required to enter a filename, the packer sets up a file
  82. requester.  This requester automatically contains all devices connected to
  83. your Amiga and lists all the files (and their length) of a selected
  84. directory.  You don't have to wait for the directory read to end.  You can
  85. select a file or directory the moment you see it, or you can enter it in the
  86. appropriate string gadget.
  87.  
  88.     However, if you wait for the directory read to end and quit the file
  89. requester, the next time you use it all the files will still be there, so you
  90. don't have to wait for the directory to be read again (This is very useful
  91. when you are recording a script, as you'll see later).  This feature has one
  92. disadvantage :  if files are changed or added to the selected directory they
  93. won't be shown in the list, or they will be shown with the wrong filelength,
  94. the next time the requester appears.  Therefore, if you think anything has
  95. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  96. the directory.  (E.g.  when you save a crunched file on top of the old one,
  97. the old file length will be shown in the requester.)
  98.  
  99.  
  100. 1.3 The basic menus
  101.  
  102. 1.3.1 Project
  103.  
  104.     The project menu contains the file manipulation options.  Most of them
  105. speak for themselves:
  106.  
  107.   Load      ->  Load a file from disk and start the (de)crunching.
  108.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  109.   Delete    ->  Delete a file from disk.
  110.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  111.   About...  ->  Show general information and my address.
  112.   Quit      ->  Quit the program.
  113.  
  114. 1.3.2 Prefs
  115.  
  116.      The prefs menu contains all (de)cruncher settings.  You can select
  117. (de)crunch command files or data files.  If you want the crunched
  118. version of your file to be executable, select 'Command file'.  Now the
  119. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  120. you want to crunch only contains data (e.g. Source codes of your own
  121. programs), select the 'Data file' option.  This can be handy if you're going
  122. to use the PowerPacker CLI commands.  I'll discuss these commands in chapter
  123. 5 of this document.  Finally you have to choose whether you want to crunch or
  124. decrunch the load file.
  125.  
  126. Note: - The PowerPacker will automatically decrunch a previously crunched
  127.         file.  You don't have to select crunch or decrunch mode anymore as
  128.         in PowerPacker 2.0a.
  129.  
  130.      The 'Decrunch Color' submenu contains the following options :
  131.  
  132.   Color 0   ->  The background color will change while decrunching
  133.   Color 1   ->  The text color changes
  134.   Pointer   ->  Only the mousepointer's color changes
  135.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  136.   None      ->  If you're eyes are wearing out.
  137.  
  138.      These options indicate what color will flash when a file is decrunching.
  139. You can change this option before saving a crunched file, so you can save a
  140. version of your crunched program that flashes in color 1, and one that
  141. flashes in the mouse pointer.
  142.      If the 'Color Crunch' option is selected, the PowerPacker will use the
  143. same color while crunching the file, giving you an idea what the decrunching
  144. will look like (provided that you don't change any options just before saving
  145. to disk).  The default value is color 1.
  146.  
  147.      In the efficiency submenu you will find the following possibilities :
  148.  
  149.   Fast      ->  Use for small files, or for quick crunch.
  150.   Mediocre  ->  Better but slower.
  151.   Good      ->  Default, gains 40-50% in most cases.
  152.   Very Good ->  Also very slow !
  153.   Best      ->  Advised for script use only, ultra slow !!!
  154.  
  155. Note: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  156.         2 times slower and 'Best' 4 times.
  157.  
  158.      You can set Amiga's multitasking off to increase the crunching speed
  159. (slightly).  The default setting is on.  When you want to use the PowerPacker
  160. in a multitasking environment, you'll probably start a crunching job and at
  161. the same time continue your work.  In that case, it might be interesting to
  162. set the 'LED Crunch' option on.  Now your power-LED flashes while crunching,
  163. just like the screencolors.  (but I presume they're already turned off
  164. because editing a file with flashing text really gets on your nerves)
  165.      You can even turn off your monitor and still see when the cruncher has
  166. finished.
  167.  
  168.      Finally, you can set the paging in the supervisor window on so you can
  169. read the crunch and hunk information, without everything racing off the
  170. screen before you've had a chance to see it.
  171.  
  172. Note: - While crunching, you can press both mousebuttons at the same
  173.         time to abort.
  174.       - Do *NOT* change disks when you are crunching with the multitasking
  175.         switched off !!!  The Amiga will crash !!!
  176.  
  177. 2. Recrunch
  178. -----------
  179.  
  180. 2.1 How ?
  181.  
  182.      This menu is provided for people who were using another cruncher or
  183. an older version of the PowerPacker.  Just select 'Recrunch File' or
  184. 'Decrunch Only' and load the file.  The PowerPacker will start the correct
  185. decrunch algorithm.  If you selected 'Recrunch' the PowerPacker will start
  186. crunching the decrunched file.  If the PowerPacker doesn't recognize the
  187. cruncher it will say so, no harm is done.
  188.  
  189.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  190. 'Relokit 1.0' and older PowerPacker files.  If you'd like to see other
  191. crunchers supported, send me the cruncher and some programs crunched with it.
  192. (With a contribution I hope).  If it is possible to develop a decrunch
  193. algorithm I will include it in the next version of the PowerPacker.
  194.  
  195. 2.2 Why ?
  196.  
  197.      The PowerPacker always crunches better than the 'ANC Cruncher' and the
  198. 'TNM Cruncher'.  It crunches better than 'Relokit' most of the time, but even
  199. if it doesn't, I advise you to recrunch because 'Relokit' has some serious
  200. disadvantages (e.g. while the decrunched file is running, the crunched
  201. version still eats memory).  In contrast the PowerPacker only eats about 580
  202. bytes while your file is running, and (of course) frees it afterwards.
  203.  
  204. Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file, the
  205.         PowerPacker just replaces the file header with the improved and
  206.         debugged 2.1 header.
  207.       - The recrunch menu only supports command files !  You can't recrunch
  208.         data files from e.g. PowerPacker 1.0, sorry.
  209.  
  210. 2. The Hunklab
  211. --------------
  212.  
  213. 2.1 Preferences
  214.  
  215.      This menu is not really part of the PowerPacker crunch/decrunch routines
  216. but it wasn't worth writing a separate program for and a HunkLab is after all
  217. a very interesting utility.  You can e.g. use it to remove symbol and debug
  218. hunks from files that wouldn't crunch otherwise.
  219.  
  220.      You can force a program's code, data or BSS (uninitialised data) into
  221. chip ram or you can remove symbol tables and debug information just by
  222. toggling the marker on/off.  So in future, when you want your programs to be
  223. able to run on a one megabyte system, a simple click on the mousebutton will
  224. do.
  225.  
  226. 2.2 Process file
  227.  
  228.      'Process file' reads the file from disk and changes it according to your
  229. preferences.  To save the processed file, use 'Save' from the Project menu.
  230.      'Process & Crunch' will process the file and crunch the file afterwards
  231. (if possible).  To save use 'Save' in the Project menu.
  232.  
  233.  
  234. 3. The Script Menu
  235. ------------------
  236.  
  237.      This menu contains a new feature in version 2.1a.  It allows you to
  238. record and execute 80 different commands.  It is ideal when crunching a lot
  239. of files overnight.  Menu options are:
  240.  
  241.      'Clear Script' and 'List Script' will do just that.
  242.      'Source Dir' and 'Destination Dir' are used to specify the directory to
  243.           load from and the directory to save to.  They are ghosted during
  244.           normal use.
  245.      'Start Recording' is used to start the recording of the script. If the
  246.           script was empty you will be asked for the destination directory.
  247.           You will also be asked whether to append '.pp21' to the destination
  248.           file.  You're advised to do this for data files.
  249.               After selecting the destination you can start entering the
  250.           script commands.  Everything that is ghosted is not available as a
  251.           command.  Just enter everything as if you were actually using the
  252.           PowerPacker.  When you e.g. choose 'Load' the PowerPacker will
  253.           ask a list of files to be (de)crunched. Press 'CANCEL' to exit the
  254.           entry.
  255.           Note: - You can still change the source and destination dir while
  256.                   recording.
  257.           Every command you enter will be displayed in the supervisor window.
  258.      'Stop Recording' is used to exit the recording mode.
  259.      'Delete Last' will delete the last command after a confirmation.
  260.      'Execute Script' finally, is used to start the playback of the script
  261.           commands.  If you press the menu button a requester will appear to
  262.           ask you if you want to abort the script execution.
  263.               After executing the script, a request to clear the script will
  264.           appear.
  265.  
  266. Note: - It is advisable to let the filerequester buffer fill before you
  267.         start selecting files.  It is also better not to change the source
  268.         directory too often.
  269.       - The screen turns grey to indicate a script is executing.
  270.       - While executing a script, the PowerPacker will always act
  271.         destructive !  Files will always be overwritten and deleted !!!
  272.  
  273. 4. The Supervisor Window
  274. ------------------------
  275.  
  276.      This window displays all kind of useful information like the file
  277. status, crunch messages, and error messages.  You can follow all steps, from
  278. the original file that is loaded into memory, to the final crunched version
  279. on disk.  When an executable file is loaded, its hunk information is
  280. displayed.  This information is rather technical, but it can be useful for
  281. programmers.  If you're not interested, just ignore it.
  282.  
  283.      I think it might be useful to give a list of possible error messages:
  284.  
  285. (De)crunch :  Buffer overflow !
  286.                 (Crunched file is getting longer than original file)
  287.               Crunch aborted !
  288.                 (Crunching stopped by user or by buffer overflow)
  289.               No memory for decrunch buffer !
  290.               Out of memory !
  291.                 (Buy some more, or try closing the WorkBench)
  292.               Sorry, can't crunch !
  293.                 (This is a polite program)
  294.               Can't find hunk_header.
  295.               Hunk not allowed in load file!
  296.               Unknown Hunk !
  297.                 (Not a command file)
  298.               Hunk not supported (yet ?) !
  299.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  300.               Nothing to save !
  301.                 (Buffer is empty)
  302.               Save Aborted !
  303.               Error reading file !
  304.               Can't open file !
  305.               Error writing data header !
  306.               Error writing buffer !
  307.               File not found !
  308.               Couldn't delete file !
  309.               Can't open file !
  310.                 (Disk errors)
  311.  
  312. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  313.               Replacing 1.1 decrunch header with 2.1 header...
  314.                 (2.1 header is shorter and bugfree, 1.1 isn't !!)
  315.               No need to recrunch 'PowerPacker 2.0' command file,
  316.               Replacing 2.0 decrunch header with 2.1 header...
  317.                 (There was still a small bug in 2.0 header giving problems
  318.                  when low on memory, so replace it.)
  319.               Not crunched with one of the supported crunchers !!
  320.                 (Or file is not crunched at all !)
  321.               Sorry, can't recrunch !
  322.                 (We're always polite)
  323.  
  324. Process :     Sorry, can't process file !
  325.                 (File is probably not a command file)
  326.               Can't crunch file !
  327.                 (File still contains unsupported hunks)
  328.  
  329. Script :      Script buffer full !! Please stop recording.
  330.                 (Script is limited to 80 commands, choose 'Stop Recording')
  331.  
  332. 5. A Sample Session
  333. -------------------
  334.  
  335.      Now that I have explained the PowerPacker's capabilities, it's time for
  336. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  337. System directory on your Workbench 1.2 disk.
  338.  
  339.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  340. text, it was very late and I couldn't stand the other decrunch colors
  341. anymore !)
  342.  
  343.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  344. (a file requester will appear), insert your WorkBench 1.2 disk and choose the
  345. 'CLI' command in the system directory.  Now you'll see a lot of hunk
  346. information about the CLI command:
  347.  
  348.                                                                              
  349.      Loading command file 'df0:System/CLI'...                                
  350.                                                                              
  351.      Hunk_header (0x03F3)                                                    
  352.         9 hunks (0 to 8).                                                    
  353.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
  354.                Hunk_reloc32 (0x03EC)                                         
  355.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
  356.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
  357.                Hunk_reloc32 (0x03EC)                                         
  358.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
  359.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
  360.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
  361.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
  362.                Hunk_reloc32 (0x03EC)                                         
  363.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
  364.                Hunk_reloc32 (0x03EC)                                         
  365.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
  366.                                                                              
  367.      Crunching command file...                                                  
  368.      Press left and right button to abort.                                   
  369.      Crunching, please wait.                                                 
  371.  
  372.      The cruncher displays the percentage of the file already crunched and
  373. after some time your screen will look like this:
  374.  
  375.                                                                              
  376.      100% crunched.                                                          
  377.      Done.                                                                   
  378.      Original length : 2356 bytes.                                           
  379.      Crunched length : 1204 (1776) bytes.                                    
  380.      Gained 49% (1152 bytes) !                                               
  382.  
  383.      The only thing you have to do now is save this back to disk as a
  384. command file.  Now enjoy the crunched CLI command.
  385.  
  386.  
  387. 6. PowerPacker 2.1a & the CLI
  388. -----------------------------
  389.  
  390.      For your convenience, I have also written two CLI commands, one to
  391. crunch and one to decrunch.
  392.      Attention:  These commands only (de)crunch DATA files !!!!  (So to
  393. crunch executable files, you'll still have to use the PowerPacker 2.1a).
  394.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  395. arguments.  You'll get something like this:
  396.  
  397. 1>
  398. 1> crunch
  399. POWER-PACKER 2.1a Data Cruncher.
  400.   Written by Lone Wolf from POWERPEAK.
  401. USAGE : Crunch <source> <destination> [efficiency (1-5) default 3] [P] [F]
  402.         Where P stands for no percentage, F for Forbid() crunching.
  403. 1>
  404. 1> decrunch
  405. POWER-PACKER 2.1a Data Decruncher.
  406.   Written by Lone Wolf from POWERPEAK.
  407. USAGE : Decrunch <source> <destination> [decrunch color (0-4)]
  408.    With decrunch color 0/1 -> Color 0/1, 2 -> Pointer, 3 -> Scroll, 4 -> None
  409.    If <destination> is a * the file will be typed to Output().
  410. 1>
  411.  
  412.      These commands are useful to be included in your startup-sequence or to
  413. read crunched text files quickly.
  414.  
  415.      I don't think these commands need any further explanation.  Just try
  416. them out and you'll see what happens.  E.g. when you have a crunched source
  417. file of a program on your disk, typing
  418.  
  419.      Decrunch filename.c *
  420.  
  421. will display the file as if you were using the 'Type' command for textfiles.
  422.  
  423.                                                    Enjoy !!!
  424.  
  425.  
  426.  
  427. P.S. This text file crunched to 43% of it's original length. (Gained 57% !)
  428.  
  429. The PowerPacker 2.1a written by François Nico (Lone Wolf).
  430. Special thanks to Pauwels Luc (Red Eagle) for writing the 2.0a manual and
  431.                   Tyberghein Jorrit (Edain) for the extensive debugging.
  432.  
  433. (c) 1989 François Nico / Power Peak
  434.  
  435.                                    //
  436.                        Thanks to \X/ Amiga for being the best computer ever !
  437.  
  438.